/*
 * Copyright (c) 2022 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef NDK_INCLUDE_NATIVE_BUFFER_H_
#define NDK_INCLUDE_NATIVE_BUFFER_H_

/**
 * @addtogroup OH_NativeBuffer
 * @{
 *
 * @brief 提供NativeBuffer功能，通过提供的接口，可以实现共享内存的申请、使用、属性查询、释放等操作。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 9
 * @version 1.0
 */

/**
 * @file native_buffer.h
 *
 * @brief 定义获取和使用NativeBuffer的相关函数。
 *
 * 引用文件<native_buffer/native_buffer.h>
 * @library libnative_buffer.so
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 9
 * @version 1.0
 */

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 提供OH_NativeBuffer结构体声明
 * @since 9
 */
struct OH_NativeBuffer;

/**
 * @brief 提供OH_NativeBuffer结构体声明
 * @since 9
 */
typedef struct OH_NativeBuffer OH_NativeBuffer;

/**
 * @brief OH_NativeBuffer的用途。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 10
 * @version 1.0
 */
enum OH_NativeBuffer_Usage {
    /**
     * CPU可读
     */
    NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0),
    /**
     * CPU可写
     */
    NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1),
    /**
     * 直接内存访问缓冲区
     */
    NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3),
};

/**
 * @brief OH_NativeBuffer的格式。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 10
 * @version 1.0
 */
enum OH_NativeBuffer_Format {
    /**
     * RGB565格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGB_565 = 3,
    /**
     * RGBA5658格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBA_5658,
    /**
     * RGBX4444格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBX_4444,
    /**
     * RGBA4444格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBA_4444,
    /**
     * RGB444格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGB_444,
    /**
     * RGBX5551格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBX_5551,
    /**
     * RGBA5551格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBA_5551,
    /**
     * RGB555格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGB_555,
    /**
     * RGBX8888格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBX_8888,
    /**
     * RGBA8888格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGBA_8888,
    /**
     * RGB888格式
     */
    NATIVEBUFFER_PIXEL_FMT_RGB_888,
    /**
     * BGR565格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGR_565,
    /**
     * BGRX4444格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRX_4444,
    /**
     * BGRA4444格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRA_4444,
    /**
     * BGRX5551格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRX_5551,
    /**
     * BGRA5551格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRA_5551,
    /**
     * BGRX8888格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRX_8888,
    /**
     * BGRA8888格式
     */
    NATIVEBUFFER_PIXEL_FMT_BGRA_8888,
    /**
     * 无效格式
     */
    NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF
};

/**
 * @brief OH_NativeBuffer的颜色空间
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 11
 * @version 1.0
 */
enum OH_NativeBuffer_ColorSpace {
    /** 无颜色空间 */
    OH_COLORSPACE_NONE,
    /** 色域范围为BT601_P， 传递函数为BT709， 转换矩阵为BT601_P， 数据范围为RANGE_FULL */
    OH_COLORSPACE_BT601_EBU_FULL,
    /** 色域范围为BT601_N， 传递函数为BT709， 转换矩阵为BT601_N， 数据范围为RANGE_FULL */
    OH_COLORSPACE_BT601_SMPTE_C_FULL,
    /** 色域范围为BT709， 传递函数为BT709， 转换矩阵为BT709， 数据范围为RANGE_FULL */
    OH_COLORSPACE_BT709_FULL,
    /** 色域范围为BT2020， 传递函数为HLG， 转换矩阵为BT2020， 数据范围为RANGE_FULL */
    OH_COLORSPACE_BT2020_HLG_FULL,
    /** 色域范围为BT2020， 传递函数为PQ， 转换矩阵为BT2020， 数据范围为RANGE_FULL */
    OH_COLORSPACE_BT2020_PQ_FULL,
    /** 色域范围为BT601_P， 传递函数为BT709， 转换矩阵为BT601_P， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_BT601_EBU_LIMIT,
    /** 色域范围为BT601_N， 传递函数为BT709， 转换矩阵为BT601_N， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_BT601_SMPTE_C_LIMIT,
    /** 色域范围为BT709， 传递函数为BT709， 转换矩阵为BT709， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_BT709_LIMIT,
    /** 色域范围为BT2020， 传递函数为HLG， 转换矩阵为BT2020， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_BT2020_HLG_LIMIT,
    /** 色域范围为BT2020， 传递函数为PQ， 转换矩阵为BT2020， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_BT2020_PQ_LIMIT,
    /** 色域范围为SRGB， 传递函数为SRGB， 转换矩阵为BT601_N， 数据范围为RANGE_FULL */
    OH_COLORSPACE_SRGB_FULL,
    /** 色域范围为P3_D65， 传递函数为SRGB， 转换矩阵为P3， 数据范围为RANGE_FULL */
    OH_COLORSPACE_P3_FULL,
    /** 色域范围为P3_D65， 传递函数为HLG， 转换矩阵为P3， 数据范围为RANGE_FULL */
    OH_COLORSPACE_P3_HLG_FULL,
    /** 色域范围为P3_D65， 传递函数为PQ， 转换矩阵为P3， 数据范围为RANGE_FULL */
    OH_COLORSPACE_P3_PQ_FULL,
    /** 色域范围为ADOBERGB， 传递函数为ADOBERGB， 转换矩阵为ADOBERGB， 数据范围为RANGE_FULL */
    OH_COLORSPACE_ADOBERGB_FULL,
    /** 色域范围为SRGB， 传递函数为SRGB， 转换矩阵为BT601_N， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_SRGB_LIMIT,
    /** 色域范围为P3_D65， 传递函数为SRGB， 转换矩阵为P3， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_P3_LIMIT,
    /** 色域范围为P3_D65， 传递函数为HLG， 转换矩阵为P3， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_P3_HLG_LIMIT,
    /** 色域范围为P3_D65， 传递函数为PQ， 转换矩阵为P3， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_P3_PQ_LIMIT,
    /** 色域范围为ADOBERGB， 传递函数为ADOBERGB， 转换矩阵为ADOBERGB， 数据范围为RANGE_LIMITED */
    OH_COLORSPACE_ADOBERGB_LIMIT,
    /** 色域范围为SRGB， 传递函数为LINEAR */
    OH_COLORSPACE_LINEAR_SRGB,
    /** 等同于 OH_COLORSPACE_LINEAR_SRGB */
    OH_COLORSPACE_LINEAR_BT709,
    /** 色域范围为P3_D65， 传递函数为LINEAR */
    OH_COLORSPACE_LINEAR_P3,
    /** 色域范围为BT2020， 传递函数为LINEAR */
    OH_COLORSPACE_LINEAR_BT2020,
    /** 等同于 OH_COLORSPACE_SRGB_FULL */
    OH_COLORSPACE_DISPLAY_SRGB,
    /** 等同于 OH_COLORSPACE_P3_FULL */
    OH_COLORSPACE_DISPLAY_P3_SRGB,
    /** 等同于 OH_COLORSPACE_P3_HLG_FULL */
    OH_COLORSPACE_DISPLAY_P3_HLG,
    /** 等同于 OH_COLORSPACE_P3_PQ_FULL */
    OH_COLORSPACE_DISPLAY_P3_PQ,
    /** 色域范围为BT2020， 传递函数为SRGB， 转换矩阵为BT2020， 数据范围为RANGE_FULL */
    OH_COLORSPACE_DISPLAY_BT2020_SRGB,
    /** 等同于 OH_COLORSPACE_BT2020_HLG_FULL */
    OH_COLORSPACE_DISPLAY_BT2020_HLG,
    /** 等同于 OH_COLORSPACE_BT2020_PQ_FULL */
    OH_COLORSPACE_DISPLAY_BT2020_PQ,
};

/**
 * @brief OH_NativeBuffer的属性配置，用于申请新的OH_NativeBuffer实例或查询现有实例的相关属性
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @since 9
 * @version 1.0
 */
typedef struct {
    /**
     * 宽度（像素）
     */
    int32_t width;
    /**
     * 高度（像素）
     */
    int32_t height;
    /**
     * 像素格式
     */
    int32_t format;
    /**
     * buffer的用途说明
     */
    int32_t usage;
    /**
     * 本地窗口缓冲区步幅
     * @since 10
     */
    int32_t stride;
} OH_NativeBuffer_Config;

/**
 * @brief 通过OH_NativeBuffer_Config创建OH_NativeBuffer实例，每次调用都会产生一个新的OH_NativeBuffer实例
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param config 一个指向OH_NativeBuffer_Config类型的指针
 * @return 创建成功则返回一个指向OH_NativeBuffer结构体实例的指针，否则返回NULL
 * @since 9
 * @version 1.0
 */
OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config);

/**
 * @brief 将OH_NativeBuffer对象的引用计数加1
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @return 返回值为0表示执行成功
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer);

/**
 * @brief 将OH_NativeBuffer对象的引用计数减1，当引用计数为0的时候，该NativeBuffer对象会被析构掉
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @return 返回值为0表示执行成功
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer);

/**
 * @brief 用于获取OH_NativeBuffer的属性
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @param config 一个指向OH_NativeBuffer_Config的指针，用于接收OH_NativeBuffer的属性
 * @since 9
 * @version 1.0
 */
void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config);

/**
 * @brief 将OH_NativeBuffer对应的ION内存映射到进程空间
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @param virAddr 一个二级指针，二级指针指向映射到当前进程的虚拟内存的地址
 * @return 返回值为0表示执行成功
 * @since 9
 * @version 1.0
 */

int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr);

/**
 * @brief 将OH_NativeBuffer对应的ION内存从进程空间移除
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @return 返回值为0表示执行成功
 * @since 9
 * @version 1.0
 */
int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer);

/**
 * @brief 获取OH_NativeBuffer的序列号
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @return 返回对应OH_NativeBuffer的唯一序列号
 * @since 9
 * @version 1.0
 */
uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer);

/**
 * @brief 为OH_NativeBuffer设置颜色空间属性
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer
 * @param buffer 一个指向OH_NativeBuffer实例的指针
 * @param colorSpace 为OH_NativeBuffer设置的颜色空间，其值从OH_NativeBuffer_ColorSpace获取
 * @return 返回值为0表示执行成功
 * @since 11
 * @version 1.0
 */
int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace);

#ifdef __cplusplus
}
#endif

/** @} */
#endif